home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / UI & Events / Implementing a Dispatch Module < prev    next >
Encoding:
Text File  |  1995-11-07  |  3.0 KB  |  54 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Recipes
  2.  
  3. Implementing a Dispatch Module
  4. By The OpenDoc Design Team
  5. November, 1995
  6.  
  7.  
  8. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  9. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  10. Mac and OpenDoc are trademarks of Apple Computer, Inc. 
  11.  
  12.  
  13. Introduction
  14.  
  15. The OpenDoc Dispatcher can be extended by developers, to handle additional event types, perhaps associated with some exotic input device like a glove. The same mechanism can also be used to “patch” the dispatcher. See Patching OpenDoc.
  16.  
  17. Note: Most developers should not need to extend or patch the dispatcher. Please think very carefully before doing so. 
  18.  
  19. ODDispatcher maintains a dictionary of dispatch modules, with the event type as the key. When ODDispatcher::Dispatch() is called, the dispatcher looks up a dispatch module for the supplied event type, and calls its Dispatch() method.
  20.  
  21. To extend the dispatcher, a developer must implement a subclass of ODDispatchModule, and install it in the dispatcher.
  22.  
  23. Defining a Dispatch Module
  24.  
  25. ODDispatchModule is a System Object Model™ (SOM) class, just like ODPart, and must be subclassed (in IDL). The subclass should have an Init<ClassName>  method, and should override the Dispatch() method:
  26.  
  27.     ODBoolean Dispatch(inout ODEventData, inout ODEventInfo)
  28.  
  29. The Init<ClassName> method should call InitDispatchModule, and the Dispatch() method will presumably locate a part to handle the event, and call its HandleEvent() method. 
  30.  
  31. New in DR3: There is a new method Redispatch() defined in ODDispatcher. When the standard OpenDoc dispatch module transforms an event (eg. mouse down into menu event), it redispatches. This means that dispatch module patches can intercept the transformed event. As a result, the Dispatch() method of ODDispatchModule now has an eventInfo parameter containing the addition information associated with some of the transformed events (eg. embedded frame).
  32.  
  33. Installing a Dispatch Module
  34.  
  35. A dispatch module should be installed by calling  ODDispatcher::AddDispatchModule:
  36.     
  37.     void AddDispatchModule(in ODEventType eventType, in ODDispatchModule dispatchModule); 
  38.  
  39. For example:
  40.  
  41.     myDispatchModule = new MyDispatchModule();
  42.     myDispatchModule->InitMyDispatchModule(ev, session);
  43.     dispatcher->AddDispatchModule(ev, kFooBarEvent, myDispatchModule);
  44.  
  45.  
  46. The installation could take place in a part's initialization method, or in a Shell Plug-In. 
  47.  
  48. Monitors
  49.  
  50. A dispatch module can also be installed as a monitor, by calling  ODDispatcher::AddMonitor() instead:    
  51.  
  52.     void AddMonitor(in ODEventType eventType, in ODDispatchModule dispatchModule);
  53.  
  54. Unlike regular dispatch modules, multiple monitors can be installed for a single event type. The dispatcher calls the Dispatch() method of all monitors for an event before calling the Dispatch() method of the single regular dispatch module for that event type. The Boolean result returned by the monitors' implementation of Dispatch() is ignored. In other words, a monitor can't interfere with the regular dispatching of the event, unless it actually changes the event type on the fly [Shudder].